﻿MotionNexa Agent 常见问题说明
版本：RC1 商业安装版

============================================================
一、安装相关问题
============================================================

问题 1：安装器打不开，或 Windows 提示未知发布者。


解决办法：
1. 确认安装包来源是 MotionNexa Agent 官网。
2. 右键安装包，选择“以管理员身份运行”。
3. 如果出现 Windows Defender SmartScreen 提示，点击“更多信息”，再点击“仍要运行”。


问题 2：安装时提示没有权限。

原因：
MotionNexa Agent 需要安装到 Adobe CEP 扩展目录，该目录位于 Program Files，通常需要管理员权限。

解决办法：
1. 关闭 Adobe After Effects。
2. 右键 MotionNexaAgent_Setup.exe。
3. 选择“以管理员身份运行”。
4. 重新安装。


问题 3：安装完成后 AE 中找不到 MotionNexa Agent 面板。

可能原因：
1. AE 没有重启。
2. CEP 扩展加载注册表未生效。
3. 安装路径不正确。
4. AE 版本过旧或不支持当前 CEP 扩展。

解决办法：
1. 完全关闭 Adobe After Effects。
2. 重新打开 AE。
3. 在 AE 顶部菜单“窗口 / Window”中查找 MotionNexa Agent。
4. 如果仍然没有，重启电脑后再打开 AE。
5. 确认安装目录存在：

   C:\Program Files (x86)\Common Files\Adobe\CEP\extensions\AEAIAGENT

6. 如果目录不存在，请重新安装。


问题 4：安装后出现多个 MotionNexa Agent 版本。

原因：
之前手动解压或测试时安装过带日期的旧版本目录。

解决办法：
1. 关闭 AE。
2. 保留当前正式目录：

   C:\Program Files (x86)\Common Files\Adobe\CEP\extensions\AEAIAGENT

3. 删除旧测试目录，例如：

   AEAIAGENT_Agent_Core_*

4. 重新打开 AE。


问题 5：卸载后重新安装，原来的服务密钥还在。

原因：
卸载程序默认只删除安装目录，不删除用户本地数据目录。

解决办法：
这是正常设计，用于避免用户升级或重装时丢失配置。
如果需要彻底清除，请手动删除：

%LOCALAPPDATA%\AEAIAGENT

注意：删除后历史记录、服务密钥、生成图片、本地配置都会丢失。


============================================================
二、购买 / 授权 / 售后规则
============================================================

问题：MotionNexa Agent 是免费的吗？

说明：
MotionNexa Agent 安装包可免费下载。付费内容为软件授权码，授权码用于激活 MotionNexa Agent 的本地辅助功能使用权限。

问题：授权码在哪里购买？

说明：
授权码请通过官方指定闲鱼店铺或客服渠道获取。请勿购买、转让、共享来历不明的授权码。

问题：授权码支持退款吗？

说明：
授权码属于数字化软件授权。授权码一经发出并完成绑定/激活，视为已交付并启用。除产品自身原因导致无法激活或无法正常使用，且经售后排查后仍无法解决外，不支持无理由退款。

以下情况通常不属于授权码本身质量问题：
1. 用户填错账号或绑定错账号。
2. 用户泄露、共享授权码或账号。
3. 用户自己的服务密钥无效、无权限、无额度。
4. 用户网络、代理、系统环境异常。
5. 用户未安装 Node.js、Codex CLI 或未按说明配置。
6. 第三方模型服务接口、价格、权限、地区限制发生变化。

问题：MotionNexa Agent 是否包含模型账号、API Key、额度或代理？

说明：
不包含。MotionNexa Agent 不提供、不销售、不代申请、不代充值任何第三方模型账号、API Key、模型额度或代理服务。用户需自行准备合法可用的第三方服务密钥，并自行承担第三方服务产生的费用、账号状态、地区限制、接口变化和内容合规责任。

问题：MotionNexa Agent 是 Adobe 官方产品吗？

说明：
不是。MotionNexa Agent 为 After Effects 本地辅助创作工具，非 Adobe 官方产品，未获得 Adobe 的官方授权、认证、赞助或背书。Adobe、After Effects 等名称仅用于说明兼容环境。

问题：为什么有些本地目录仍显示 AEAIAGENT？

说明：
为兼容旧版本升级和保留用户本地密钥、历史记录、生成图片，部分内部安装目录或本地数据目录仍可能显示为 AEAIAGENT，这是历史内部目录名，不影响使用。


============================================================
三、登录 / 授权问题
============================================================

问题 6：登录成功后，界面仍停留在登录页。

可能原因：
1. 本地 runtime 状态没有及时刷新。
2. 面板缓存状态异常。
3. 旧版本残留目录被 AE 加载。

解决办法：
1. 关闭 AE。
2. 重新打开 AE。
3. 再次打开 MotionNexa Agent 面板。
4. 确认 AE 当前加载的是正式目录 MotionNexa Agent，而不是旧测试目录。
5. 如果仍然异常，退出账号后重新登录。


问题 7：提示授权码无效。

可能原因：
1. 授权码输入错误。
2. 复制时带了空格或换行。
3. 授权码不是当前平台发放的有效授权码。

解决办法：
1. 重新复制授权码。
2. 删除前后空格。
3. 注意区分数字 0 和字母 O。
4. 注意区分数字 1 和字母 I。
5. 如果仍然无效，请联系售后核对授权码状态。


问题 8：提示授权码已被使用。

原因：
授权码通常只能绑定一个账号。

解决办法：
1. 确认是否已经用其它邮箱激活过。
2. 如果是误绑，请联系售后处理。
3. 不要把授权码分享给他人。


问题 9：换电脑后无法使用授权。

可能原因：
当前授权策略限制设备或登录状态。

解决办法：
1. 先在旧电脑退出账号。
2. 在新电脑登录同一账号。
3. 如果仍然无法使用，请联系售后解绑或重置设备状态。


问题 10：网页端找不到授权码输入入口。

原因：
当前设计为：网页只负责注册、登录和下载安装包；授权码需要在 AE 面板中激活。

解决办法：
1. 下载并安装 MotionNexa Agent。
2. 打开 AE。
3. 打开 MotionNexa Agent 面板。
4. 在 AE 面板中输入授权码激活。


============================================================
三、服务密钥 / API Key 问题
============================================================

问题 11：测试连接失败。

可能原因：
1. 服务密钥填写错误。
2. 服务密钥没有权限。
3. Base URL 填写错误。
4. 网络无法连接服务商接口。
5. 代理设置异常。

解决办法：
1. 重新复制服务密钥。
2. 确认没有复制多余空格。
3. Base URL 不确定时先使用默认值。
4. 检查网络是否能访问对应服务商。
5. 如果使用代理，确认代理地址和端口正确。
6. 清除本机密钥后重新保存。


问题 12：清除密钥后，重新保存仍显示没有密钥。

解决办法：
1. 确认当前使用的是最新安装器版本。
2. 重新输入完整服务密钥。
3. 点击保存。
4. 点击测试连接。
5. 如果仍然异常，关闭 AE 后重新打开再试。


问题 13：服务密钥会不会上传到外泄？

说明：
不会。服务密钥保存在用户本机，用于本地 runtime 调用模型服务。


问题 14：提示模型没有权限或模型不可用。

可能原因：
1. 用户自己的服务密钥没有对应模型权限。
2. 服务商账号额度不足。
3. Base URL 指向的服务商不支持当前模型。

解决办法：
1. 检查服务商后台模型权限。
2. 检查余额或额度。
3. 更换有权限的服务密钥。
4. 确认 Base URL 与服务商文档一致。


============================================================
四、本地 runtime / 连接问题
============================================================

问题 15：报错 connect ECONNREFUSED 127.0.0.1:39393。

含义：
MotionNexa Agent 前端无法连接本地 Node runtime。

可能原因：
1. 本地 runtime 没启动。
2. Node.js 未安装或版本异常。
3. 端口被占用。
4. 安装目录损坏。
5. 杀毒软件拦截。

解决办法：
1. 关闭 AE。
2. 打开任务管理器，结束残留 node.exe。
3. 重新打开 AE。
4. 确认已安装 Node.js 20 或以上版本。
5. 重新安装 MotionNexa Agent。
6. 如果仍然失败，联系售后并提供日志。


问题 16：报错 spawn EINVAL。

含义：
本地进程启动失败，通常和命令路径、Node、Codex CLI 或系统环境有关。

解决办法：
1. 确认使用的是最终稳定安装版，不要使用 runtime exe 实验包。
2. 确认 Node.js 可正常运行。
3. 确认 Codex CLI 可正常运行。
4. 关闭 AE 后重新打开。
5. 如果持续出现，请联系售后提供 codex-spawn-debug.log。


问题 17：一键诊断里 runtime 失败。

解决办法：
1. 关闭 AE。
2. 结束 node.exe。
3. 重新打开 AE。
4. 重新运行一键诊断。
5. 如果仍失败，重新安装 MotionNexa Agent。


问题 18：一键诊断里 Node 版本警告。

原因：
Node.js 版本过低或路径异常。

解决办法：
1. 安装 Node.js 20 或以上版本。
2. 安装后重启电脑。
3. 重新打开 MotionNexa Agent。


问题 19：一键诊断里 Codex CLI 失败。

可能原因：
1. 未安装 Codex CLI。
2. Codex CLI 不在 PATH 中。
3. 当前系统权限无法调用 Codex CLI。

解决办法：
1. 安装 Codex CLI。
2. 安装后重启电脑。
3. 打开命令行确认 codex 命令可用。
4. 重新运行一键诊断。


============================================================
五、AE 执行任务问题
============================================================

问题 20：点击发送后没有反应。

可能原因：
1. 当前未登录。
2. 当前未授权。
3. 服务密钥未保存。
4. 本地 runtime 未启动。
5. AE 当前没有合成。

解决办法：
1. 确认已登录。
2. 确认已授权。
3. 确认服务密钥测试连接成功。
4. 新建或打开一个 AE 合成。
5. 先测试简单任务：

   创建一个红色纯色层，命名为 TEST_RED


问题 21：AI 返回了内容，但 AE 画面没有变化。

可能原因：
1. AE 当前没有活动合成。
2. AE 脚本执行被阻止。
3. 任务描述不够明确。
4. Codex/MCP 执行链路异常。

解决办法：
1. 打开一个合成并选中时间线。
2. 用简单任务测试：创建红色纯色层 TEST_RED。
3. 重新发送任务。
4. 如果简单任务也失败，请导出诊断包联系售后。


问题 22：任务执行很慢。

可能原因：
1. 模型响应慢。
2. 网络连接慢。
3. 任务复杂。
4. AE 工程较大。
5. 当前电脑性能不足。

解决办法：
1. 先用简单任务测试速度。
2. 减少一次性任务复杂度。
3. 检查网络和代理。
4. 关闭不必要的软件。
5. 等当前任务完成后再发送新任务。


问题 23：任务中途失败。

解决办法：
1. 查看面板中的错误提示。
2. 重新发送更明确的任务。
3. 先测试 TEST_RED 简单任务。
4. 如果简单任务正常，说明基础链路没问题，可能是任务过复杂或描述不明确。
5. 如果简单任务也失败，请导出诊断包联系售后。


问题 24：停止任务后，再发送任务异常。

解决办法：
1. 等待几秒后再发送。
2. 如果仍异常，关闭 AE 后重新打开。
3. 避免频繁连续点击停止和发送。


============================================================
六、图片生成问题
============================================================

问题 25：普通生图失败。

可能原因：
1. 服务密钥不支持图片模型。
2. Base URL 不支持图片接口。
3. 网络或代理异常。
4. 图片提示词被服务商拒绝。

解决办法：
1. 确认服务密钥支持图片生成。
2. 检查 Base URL。
3. 换一个简单提示词测试。
4. 检查代理和网络。


问题 26：上传参考图后没有被使用。

解决办法：
1. 确认参考图已成功上传。
2. 确认面板中能看到参考图预览。
3. 在提示词中明确写“参考上传图片”。
4. 重新上传图片再试。


问题 27：当前帧参考图没有生效。

可能原因：
1. AE 当前没有活动合成。
2. 当前合成画面没有正常显示。
3. 提示词没有明确表达使用当前画面。

解决办法：
1. 打开一个 AE 合成。
2. 确认预览窗口里能看到当前画面。
3. 使用类似表达：

   参考当前画面生成一张图
   根据当前帧继续生成
   使用当前画面作为参考图

4. 重新发送。


问题 28：当前帧参考图预览裂图。

解决办法：
1. 关闭 MotionNexa Agent 面板后重新打开。
2. 重新截取当前帧。
3. 确认本地 runtime 正常运行。
4. 如果仍然异常，导出诊断包联系售后。


问题 29：连续普通生图时，上一张图被误当成参考图。

说明：
最新版已修复该问题。

解决办法：
1. 确认使用的是最新安装器版本。
2. 普通生图时不要勾选或上传参考图。
3. 如果仍然出现，请记录操作步骤并联系售后。


============================================================
七、代理 / 网络问题
============================================================

问题 30：不使用代理时连接失败。

可能原因：
当前网络无法直接访问模型服务商。

解决办法：
1. 检查网络是否能访问服务商官网。
2. 如果需要代理，请在设置中填写代理地址。
3. 代理格式请按面板要求填写。


问题 31：使用代理后仍然失败。

解决办法：
1. 确认代理软件已启动。
2. 确认代理端口正确。
3. 确认代理支持 HTTPS 请求。
4. 尝试关闭代理后再测试。
5. 检查服务密钥是否有效。


问题 32：测试连接成功，但发送任务失败。

可能原因：
1. 测试连接只验证基础 API，任务执行还需要 Codex CLI 和 MCP 链路。
2. Codex CLI 环境异常。
3. AE 当前上下文异常。

解决办法：
1. 运行一键诊断。
2. 测试 TEST_RED 简单任务。
3. 确认 Codex CLI 正常。
4. 如果仍失败，导出诊断包。


============================================================
八、文件 / 权限 / 杀毒软件问题
============================================================

问题 33：杀毒软件提示风险。

原因：
MotionNexa Agent 会在本地启动 Node runtime，并与 AE 进行本地通信，部分安全软件可能误报。

解决办法：
1. 确认安装包来自 MotionNexa Agent 官网。
2. 将 MotionNexa Agent 安装目录加入信任列表。
3. 将 %LOCALAPPDATA%\AEAIAGENT 加入信任列表。
4. 如果仍然拦截，请联系售后。


问题 34：安装目录无法写入。

原因：
安装目录位于 Program Files，需要管理员权限。

解决办法：
1. 右键安装器。
2. 选择“以管理员身份运行”。
3. 不要手动把文件复制到受限目录。


问题 35：日志文件在哪里？

常见日志目录：

%LOCALAPPDATA%\AEAIAGENT\logs

常见日志文件可能包括：

- diagnostics-runtime.log
- diagnostics-ui.log
- codex-spawn-debug.log
- runtime-exe-http.log（如果曾安装过实验包）

正式稳定版一般不需要 runtime-exe 相关日志。


问题 36：诊断包应该怎么发给售后？

解决办法：
1. 打开 MotionNexa Agent 面板。
2. 点击一键诊断。
3. 导出诊断包。
4. 把诊断包发给售后。
5. 不要单独发送服务密钥、授权码、账号密码。


============================================================
九、升级 / 版本问题
============================================================

问题 37：更新后旧问题仍然存在。

可能原因：
1. AE 加载了旧扩展目录。
2. 安装后没有重启 AE。
3. 浏览器/面板缓存未刷新。

解决办法：
1. 关闭 AE。
2. 删除旧的 AEAIAGENT_Agent_Core_* 测试目录。
3. 保留正式目录 MotionNexa Agent。
4. 重新运行安装器。
5. 重新打开 AE。


问题 38：覆盖安装会不会删除密钥？

不会。
覆盖安装不会删除：

- 服务密钥
- 授权状态
- 历史记录
- 生成图片
- 本地配置

这些数据保存在：

%LOCALAPPDATA%\AEAIAGENT


问题 39：换版本后需要重新授权吗？

一般不需要。
如果本地授权状态失效，请重新登录账号，让面板重新同步授权状态。


============================================================
十、售后排查建议
============================================================

遇到问题时，请先按顺序确认：

1. AE 是否已经重启。
2. 是否使用最新安装器。
3. 是否已经登录。
4. 是否已经授权。
5. 服务密钥测试连接是否成功。
6. Node.js 是否安装。
7. Codex CLI 是否安装。
8. 是否能执行 TEST_RED 简单任务。
9. 一键诊断是否有失败项。
10. 是否存在旧版本扩展目录。

联系售后时，请提供：

1. 问题截图。
2. 报错文字。
3. Windows 版本。
4. AE 版本。
5. MotionNexa Agent 安装器版本。
6. 一键诊断截图或诊断包。
7. 复现步骤。

请不要提供：

1. 服务密钥。
2. 授权码完整内容。
3. 账号密码。
4. 其它敏感个人信息。


============================================================
十一、建议用户首次验证用语
============================================================

安装后可以先测试以下任务：

1. 创建一个红色纯色层，命名为 TEST_RED。
2. 创建一个蓝色文本，内容为 HELLO MotionNexa Agent。
3. 参考当前画面生成一张更有电影感的图片。
4. 根据上传参考图生成同风格画面。

如果这些都能正常执行，说明基础安装、授权、服务密钥、模型调用和 AE 执行链路基本正常。
